feat!: Persist utxo lock status #259

ValuedMammal · 2025-06-07T19:23:41Z

This PR adds methods to Wallet to lock and unlock a UTXO by outpoint, to query the locked outpoints, and updates the wallet ChangeSet to persist the lock status of an outpoint.

fixes #166
fixes #245

Considerations for broadcast scenarios:

When a UTXO is locked, it won't be selected for a transaction. This is useful in cases where the user needs to permanently exclude an outpoint from being spent, or reserve it until some time in the future and continue making transactions in the meantime. To eventually spend the coin the user has to explicitly unlock it. This process could perhaps be facilitated by implementing an automatic lock expiry based on block height.

If you submit a transaction to the network and then lock the inputs, then they won't be re-selected in subsequent transactions. This prevents us from inadvertently "double-spending" ourselves. Once broadcast, the lock effect depends on the fate of the transaction: If it confirms and the outpoint is still locked, then the lock is no longer useful, because the input can't be double spent anyway by virtue of consensus. If a conflict confirms, the lock is also irrelevant because it already got double spent.

If the transaction is somehow dropped from the mempool but otherwise still valid, we can either rebroadcast the tx or create a replacement. As far as I can tell the implementation doesn't prevent us from creating a Replace-By-Fee transaction regardless of the lock status, since the inputs to the RBF are considered "manually selected".

To avoid the risk of double payment (sending two txs to the same payment invoice) one needs to examine the details of the second transaction to ensure that it actually replaces the first one, otherwise we've simply made a donation to our counterparty.

Changelog notice

Added these methods to `Wallet`

    - `lock_outpoint`
    - `unlock_outpoint`
    - `list_locked_outpoints`
    - `list_locked_unspent`
    - `is_outpoint_locked`

Added

   - New type `wallet::locked_outpoints::ChangeSet`
   - BREAKING: New member field `wallet::ChangeSet::locked_outpoints`

Checklists

All Submissions:

New Features:

I've added tests for the new feature
I've added docs for the new feature
This pull request breaks the existing API
I'm linking the issue being fixed by this PR

coveralls · 2025-06-07T19:27:49Z

Pull Request Test Coverage Report for Build 16851016230

Details

102 of 122 (83.61%) changed or added relevant lines in 4 files are covered.
1 unchanged line in 1 file lost coverage.
Overall coverage increased (+0.02%) to 84.936%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
wallet/src/wallet/changeset.rs	46	50	92.0%
wallet/src/wallet/persisted.rs	0	6	0.0%
wallet/src/wallet/mod.rs	50	60	83.33%

Files with Coverage Reduction	New Missed Lines	%
wallet/src/wallet/mod.rs	1	82.02%

Totals
Change from base Build 16786013135:	0.02%
Covered Lines:	6766
Relevant Lines:	7966

💛 - Coveralls

ChidiChuks · 2025-06-08T14:20:31Z

How do you handle UTXO locking in concurrent wallet instances?

nymius

Could you expand a little bit more on how this mechanism could be used in broadcast scenarios?
From the test I guess all the logic of why a UTxO becomes available again is kept by the lib user? Like unlock UTxO after a height in the future if there is not transaction spending it in the blockchain.

This is a competing solution for #257, right?

evanlinjin · 2025-06-09T01:15:56Z

How do you handle UTXO locking in concurrent wallet instances?

@ChidiChuks could you be a bit more specific with this question? Do you mean sharing lock status between multiple instances of the same wallet?

evanlinjin · 2025-06-09T02:15:58Z

This is a competing solution for #257, right?

@nymius My understanding is that this is NOT a competing solution with #257. UTXO-locking will not fully solve #166 as we want unbroadcasted outputs to be available for selection. In fact, UTXO-locking is already available by using TxBuilder::add_unspendable. The only difference here is that locked outpoints are persisted with BDK. So this is more of a convenience feature that users are requesting.

evanlinjin

Thanks for this work.

I propose adding the following methods:

list_locked_outpoints - Lists all locked outpoints.
list_locked_unspents - Lists locked outpoints that are unspent.

Imagine a situation where the caller broadcasts a tx and locks the prevouts. Then the tx gets evicted from the mempool. It will be helpful to list locked unspents at this point to recover those prevouts.

wallet/src/wallet/mod.rs

ValuedMammal · 2025-06-16T17:45:25Z

@evanlinjin I took all of your suggestions other than I think the proposed Wallet::list_locked_unspents is not yet implemented. edit: I have some ideas for this though.

wallet/src/wallet/changeset.rs

wallet/src/wallet/mod.rs

notmandatory

I'm happy to see this feature moving along. In addition to helping L2 users like @tnull it also helps support one of my personal goals of improving feature parity with the bitcoin core wallet.

clippy.toml

wallet/src/wallet/changeset.rs

notmandatory · 2025-06-25T21:47:07Z

wallet/src/wallet/mod.rs

+    }
+
+    /// List unspent outpoints that are currently locked.
+    pub fn list_locked_unspent(&self) -> impl Iterator<Item = OutPoint> + '_ {


⛏️ a nit, it's a little confusing to refer to the outpoints as "unspent" here and "outpoints" in the other new functions. Since we already have the "list_unspent" function would it make sense to use "unspent" for all the related functions (ie. locked_unspent, is_unspent_locked, lock_unspent, unlock_unspent)? Even though we all know what "outpoints" mean for those unfamiliar with bitcoin internals it's not a very descriptive term.

I think it is okay since unspent here is short for unspent_outpoint whereas outpoint elsewhere is short for outpoints which can be unspent/spent.

wallet/src/wallet/mod.rs

evanlinjin

Implementation looks good. Just need a bit more clarity on expiration_height before ACK.

wallet/src/wallet/mod.rs

wallet/src/wallet/changeset.rs

wallet/src/wallet/mod.rs

evanlinjin · 2025-08-01T15:36:59Z

wallet/src/wallet/mod.rs

+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+#[non_exhaustive]
+pub struct UtxoLock {
+    /// Outpoint.
+    pub outpoint: OutPoint,
+    /// Whether the outpoint is locked.
+    pub is_locked: bool,
+}


I think we can get away with removing this for now.

Internally, we can use locked_outpoints: Map<OutPoint, Option<bool>>.

We can have list_locked_outpoints() -> Iterator<OutPoint> instead of locked_outpoints() -> Map<OutPoint, UtxoLock>.

Good point.

New APIs added for locking and unlocking a UTXO by outpoint and to query the locked outpoints. Locking an outpoint means that it is excluded from coin selection. - Add `Wallet::lock_outpoint` - Add `Wallet::unlock_outpoint` - Add `Wallet::is_outpoint_locked` - Add `Wallet::list_locked_outpoints` - Add `Wallet::list_locked_unspent` `test_lock_outpoint_persist` tests the lock/unlock functionality and that the lock status is persistent. BREAKING: Added `locked_outpoints` member field to ChangeSet. A SQLite migration is included for adding the locked outpoints table.

..by `Box`ing the descriptor in `LoadMismatch` enum, and by boxing the ChangeSet in `DataAlreadyExists` variant of `CreateWithPersistError`. We allow the large_enum_variant lint for `FileStoreError` for now, as it is planned to be fixed in a future version of `bdk_file_store`.

github-project-automation bot added this to BDK Wallet Jun 7, 2025

ValuedMammal moved this to Todo in BDK Wallet Jun 7, 2025

ValuedMammal added this to the Wallet 3.0.0 milestone Jun 7, 2025

ValuedMammal self-assigned this Jun 7, 2025

nymius reviewed Jun 8, 2025

View reviewed changes

evanlinjin requested changes Jun 9, 2025

View reviewed changes

wallet/src/wallet/mod.rs Outdated Show resolved Hide resolved

wallet/src/wallet/mod.rs Outdated Show resolved Hide resolved

wallet/src/wallet/mod.rs Outdated Show resolved Hide resolved

notmandatory mentioned this pull request Jun 12, 2025

Introduce IntentTracker #257

Draft

14 tasks

ValuedMammal commented Jun 16, 2025

View reviewed changes

wallet/src/wallet/mod.rs Outdated Show resolved Hide resolved

ValuedMammal force-pushed the feat/lock-unspent branch from b083dff to a6b0f5d Compare June 16, 2025 17:23

ValuedMammal marked this pull request as ready for review June 16, 2025 17:29

ValuedMammal moved this from Todo to Needs Review in BDK Wallet Jun 16, 2025

ValuedMammal force-pushed the feat/lock-unspent branch from a6b0f5d to 13e024d Compare June 18, 2025 13:19

ValuedMammal moved this from Needs Review to In Progress in BDK Wallet Jun 18, 2025

evanlinjin reviewed Jun 19, 2025

View reviewed changes

wallet/src/wallet/changeset.rs Outdated Show resolved Hide resolved

wallet/src/wallet/changeset.rs Outdated Show resolved Hide resolved

wallet/src/wallet/mod.rs Outdated Show resolved Hide resolved

ValuedMammal moved this from In Progress to Needs Review in BDK Wallet Jun 23, 2025

notmandatory reviewed Jun 25, 2025

View reviewed changes

notmandatory added new feature New feature or request api A breaking API change labels Jun 25, 2025

evanlinjin reviewed Jun 26, 2025

View reviewed changes

wallet/src/wallet/mod.rs Show resolved Hide resolved

wallet/src/wallet/changeset.rs Outdated Show resolved Hide resolved

wallet/src/wallet/mod.rs Outdated Show resolved Hide resolved

ValuedMammal moved this from Needs Review to In Progress in BDK Wallet Jun 27, 2025

ValuedMammal force-pushed the feat/lock-unspent branch 2 times, most recently from 37fac7d to ee0a88b Compare July 14, 2025 17:26

evanlinjin reviewed Aug 1, 2025

View reviewed changes

ValuedMammal force-pushed the feat/lock-unspent branch 2 times, most recently from 892ffd0 to a6381de Compare August 3, 2025 22:00

ValuedMammal added 2 commits August 8, 2025 10:48

ValuedMammal force-pushed the feat/lock-unspent branch from a6381de to d020559 Compare August 8, 2025 14:55

ci: fix clippy check to exclude example crates

977034c

ValuedMammal modified the milestones: Wallet 3.0.0, Wallet 3.1.0 Aug 13, 2025

ValuedMammal moved this from In Progress to Needs Review in BDK Wallet Aug 13, 2025

feat!: Persist utxo lock status #259

Are you sure you want to change the base?

feat!: Persist utxo lock status #259

Conversation

ValuedMammal commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Considerations for broadcast scenarios:

Changelog notice

Checklists

All Submissions:

New Features:

Uh oh!

coveralls commented Jun 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 16851016230

Details

💛 - Coveralls

Uh oh!

ChidiChuks commented Jun 8, 2025

Uh oh!

nymius left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanlinjin commented Jun 9, 2025

Uh oh!

evanlinjin commented Jun 9, 2025

Uh oh!

evanlinjin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ValuedMammal commented Jun 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

notmandatory left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

notmandatory Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

evanlinjin Jul 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

evanlinjin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evanlinjin Aug 1, 2025

Choose a reason for hiding this comment

Uh oh!

ValuedMammal Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ValuedMammal commented Jun 7, 2025 •

edited

Loading

coveralls commented Jun 7, 2025 •

edited

Loading

nymius left a comment •

edited

Loading

ValuedMammal commented Jun 16, 2025 •

edited

Loading

notmandatory Jun 25, 2025 •

edited

Loading